Using PATCH requests

PATCH requests use the JSON Patch format (see http://jsonpatch.com). However, do not use "application/json-patch+json" as Content-Type, just use "application/json".

Note: The live Swagger-based API reference may show incorrect model information for PATCH requests - please use the information in this page.

'Single item' PATCH requests

There are PATCH requests in the PlanningSpace API which make changes to a single user account, role definition, or workgroup definition.

In these cases, the body of the PATCH request must be an array of patch operations, such as:

PATCH /PlanningSpace/api/v1/users/157
Content-Type: "application/json"
[ {"value": true, "path":"/isAccountLocked", "op": "replace"} ]

or

PATCH /PlanningSpace/api/v1/users/156
Content-Type: "application/json"	
[ {"value": true, "path":"/isDeactivated", "op": "replace"}, {"value":"DEACTIVATED user account", "path": "/description", "op": "replace"} ]

The response to a successful patch will be an object with key "entity" and value equal to the settings of the modified (in this case) user account (output is abbreviated):

{"entity":{"id":157,"displayName":"IPS_Admin_User2", ... }}

Notes for using PATCH requests:

  • the PATCH operations may be applied in any order by the IPS server;
  • if any operation fails then the whole PATCH request will be aborted;
  • the JSON Patch 'test' operation is not currently implemented by the Web API.

Bulk PATCH requests

The 'bulk' PATCH requests are used to change multiple user accounts, roles or workgroups.

In these cases, the body of the PATCH request must be a JSON object where each member key is an ID and each value is an array of patch operations. For example, the two PATCH examples above can be combined into one request using '/PlanningSpace/api/v1/users/bulk':

PATCH /PlanningSpace/api/v1/users/bulk
Content-Type: "application/json"
{"156": [{"value": true, "path":"/isDeactivated", "op": "replace"}, {"value":"DEACTIVATED user account", "path": "/description", "op": "replace"}],
 "157": [{"value": true, "path":"/isAccountLocked", "op": "replace"}] }

Each member will be processed separately and the response will contain, for each key, the status code (200, or an error code), and the modified entity or an error response. For example (output is abbreviated):

{"156":{"statusCode":200,"response":{"entity": {...}},
 "157":{"statusCode":200,"response":{"entity": {...}}}}

Code sample (PowerShell): Role management using PATCH operations on a workgroup

The following example uses the PowerShell command 'Invoke-RestMethod', and standard object manipulation commands, to make Web API requests. These commands will work in any standard PowerShell environment.

First, create a string to contain the server/tenant URL for your own API endpoint:

PS> $tenantUrl = 'https://ipsserver.mycompany.com/TENANTNAME'

And run an authentication request to start a Web API session, for the current Windows user account. If successful, the variable '$apiSession' will contain the session cookie:

PS> Invoke-RestMethod -Method Post -Uri "$tenantUrl/api/authentication/logon?sso=true" `
-headers @{'Content-Type'= 'application/json'} `
-body '{"useWindowsAuthentication": true}' -UseDefaultCredentials -SessionVariable apiSession

Workgroups are used to control how users are allowed to access resources in Planning Space, or permissions to modify configuration of Planning Space applications. The following command creates a new workgroup as a means to control access to the Economics application:

PS> Invoke-RestMethod -Method POST -Uri "$tenantUrl/PlanningSpace/api/workgroups" -headers @{'Content-Type'= 'application/json'}`
-body '{"name":"Economics_Users","description":"Workgroup for access to the Economics application"}' -WebSession $apiSession | ConvertTo-Json

At this stage the workgroup is not associated with any user accounts or roles, as this GET shows:

PS> Invoke-RestMethod -Method GET -Uri "$tenantUrl/PlanningSpace/api/workgroups/3" -WebSession $apiSession | ConvertTo-Json
{
"id": 3,
"name": "Economics_Users",
"description": "Workgroup for access to the Economics application",
"comments": "",
"isEveryoneWorkgroup": false,
"isAdministratorWorkgroup": false,
"users": {},
"allowedRoles": {},
"deniedRoles": {}
}

The role 'Log on to Economics' (id=8) needs to be added to the workgroup's allowedRoles object, with a PATCH request as follows:

PS> Invoke-RestMethod -Method PATCH -Uri "$tenantUrl/PlanningSpace/api/v1/workgroups/3" -WebSession $apiSession `
-Headers @{'Content-Type'= 'application/json'} -body '[{"op":"add", "path":"/allowedRoles/8" , "value":{"name":"Log on to Economics", "link":"/roles/8"}}]' | `
ConvertTo-Json
{
"entity": {
"id": 3,
"name": "Economics_Users",
"description": "Workgroup for access to the Economics application",
"comments": "",
"isEveryoneWorkgroup": false,
"isAdministratorWorkgroup": false,
"users": {},
"allowedRoles": {
"8": "@{name=Log on to Economics; link=/roles/8}"
},
"deniedRoles": {}
}}

And a second PATCH operation is required to add a user account (for user id=3) to the workgroup:

PS> Invoke-RestMethod -Method PATCH -Uri "$tenantUrl/PlanningSpace/api/v1/workgroups/3" -WebSession $apiSession `
-Headers @{'Content-Type'= 'application/json'} -body '[{"op":"add", "path":"/users/3", "value":{"name":"John Smith", "link":"/users/3"}}]' | `
ConvertTo-Json
{
"entity": {
"id": 3,
"name": "Economics_Users",
"description": "Workgroup for access to the Economics application",
"comments": "",
"isEveryoneWorkgroup": false,
"isAdministratorWorkgroup": false,
"users": {
"3": "@{name=john.smith; link=/users/3}"
},
"allowedRoles": {
"8": "@{name=Log on to Economics; link=/roles/8}"
},
"deniedRoles": {}
}}

You can do multiple patch ops for one workgroup in the same request, for example to add/remove multiple users, or modify multiple role access/deny permissions.

Note that a PATCH request will abort (no changes) if one patch op fails, therefore it may be simpler to do more PATCH requests with single or only a few ops in each request.